âšī¸ Overview
GnollHack is actively developed for Android, iOS, and Windows using a modern .NET MAUI codebase. Legacy versions of the game (such as Xamarin.Forms and native Win32/ASCII clients) are deprecated and no longer maintained.
Here is a quick directory of key design and structure documentation:
đ§âđģ Modern Client Development (.NET MAUI)
This is the primary technology stack for GnollHack development. It compiles a single C# codebase targeting mobile and desktop platforms.
đĸ Important: If you are new to the codebase, you must read this first:
- Overview of Building GnollHack with .NET MAUI â Explains how the native C library, the C# wrapper, and build-time tools interact. Skipping this is the #1 reason developers struggle to build the game.
âī¸ Essential Guides & Setup
These files contain complex development instructions that may require some time to digest:
- Instructions for Developing GnollHackM Project (.NET MAUI)
- Updating Tileset for GnollHackM (.NET MAUI)
- Known Working Build Setups
đĄ Tip: Before setting up your machine, check the Known Working Build Setups to ensure your OS and SDK versions match a verified configuration.
đ ī¸ Modern Client Build Instructions
Detailed, step-by-step guides for compiling the modern application:
- Windows: Build Instructions for WinUI3 Version on Windows (.NET MAUI)
- Android: Build Instructions for Android Version on Windows (.NET MAUI)
- iOS: Build Instructions for iOS Version on Windows (.NET MAUI)
â ī¸ Warning (Common Pitfall): Ensure that the .NET MAUI workload is fully installed inside Visual Studio. Missing platform workloads (Android/iOS) will cause project loading errors.
â Troubleshooting & Technical Reference
- Troubleshooting Building GnollHack with .NET MAUI â Covers Xamarin-to-MAUI SDK issues, MSBuild path conflicts, and keystore errors.
- Data File Locations (WinUI 3 Version â .NET MAUI) â Shows where settings and save files are stored.
- System Requirements for Modern Windows Port (.NET MAUI â WinUI 3)
- CPU and GPU Usage Modes in Modern Windows Port (.NET MAUI â WinUI 3)
đ Publishing Checklist
- Steam Version Publishing Checklist â Covers codesigning, packaging, and Steamworks integration.
âšī¸ Additional Information
đĨī¸ Modern Client Supported Platforms
The table below summarizes support for the modern client. Note that emulator performance varies, and platform support is subject to CPU architecture availability.
| Platform | Technology | CPU Arch | Solution | Projects | Emulator Support1 |
|---|---|---|---|---|---|
| Android | .NET MAUI | Arm64, x642 | GnollHackM | GnollHackM | Yes4 |
| iOS | .NET MAUI | Arm64 | GnollHackM | GnollHackM | Yes4 |
| Windows | .NET MAUI | x64, (Arm643) | GnollHackM | GnollHackM | No5 |
- 1 Emulator support refers to whether the port is supported by popular cross-operating-system emulators.
- 2 Android x64 binaries are used by Android emulators running on a Windows machine with an x64 CPU, such as the Google Play Games for PC emulator.
- 3 .NET MAUI supports Arm64 on Windows, but we have not built Arm64 binaries because we do not have a Windows test device with an Arm64 CPU.
- 4 May exhibit odd behavior or crash.
- 5 GnollHack's modern Windows port (.NET MAUI) does not run on Wine or Proton because they do not support running WinUI 3 applications.
đģ Future Platform Support
- Support for macOS using .NET MAUI / Mac Catalyst or Avalonia UI is planned, though implementation may take some time.
- Linux support for the modern client is planned using Avalonia UI, pending the maturity of the technology stack.
- Currently, there are no plans to support gaming consoles or controllers (such as the Steam Deck).
đ Background Articles
These articles provide historical context and technical background. They are easy to digest and are highly recommended for developers who want to understand the choices behind our architecture.
- Mobile Version Development History (Xamarin.Forms) â The history of early mobile client versions of GnollHack.
- Benefits of .NET MAUI over Xamarin.Forms â Explains the single-project benefits and performance gains of modernizing the UI.
đ Additional Technical Information
- Release Checklist
- Native Libraries
- Debugging Linux Version in WSL using Visual Studio Code
- SkiaSharp Build Instructions â Describes custom SkiaSharp compilations (primarily for reference).
đ Legacy Clients (Obsolete)
đ Caution: The following sections describe legacy versions and ports that are no longer actively supported or maintained. They are kept here for historical reference only. Do not use these targets for active feature development.
đą Legacy Mobile Ports (Xamarin.Forms)
- Build Instructions for Android Version on Windows
- Android Version Building Checklist
- Build Instructions for iOS Version on Windows
đĨī¸ Legacy Windows Ports (1990s UI Style)
- Build Instructions for ASCII Version on Windows â Win32 Console Application
- Build Instructions for Windows GUI Version on Windows â Win32 Application with ComCtl32 Controls
đģ Legacy Linux Port
đ Legacy Clients Support Table
| Platform | Technology | CPU Arch | Solution | Projects | Emulator Support1 |
|---|---|---|---|---|---|
| Android | Xamarin.Forms | Arm64 | GnollHack | GnollHackX, GnollHackX.Android | Yes3 |
| iOS | Xamarin.Forms | Arm64 | GnollHack | GnollHackX, GnollHackX.iOS | Yes3 |
| Windows | ASCII | x64 | GnollHack | GnollHack | Yes |
| Windows | ComCtl32 Controls | x64 | GnollHack | GnollHackW | Yes |
| Linux | ASCII | x64 | N/A2 | N/A2 | N/A |
- 1 Emulator support refers to whether the port is supported by popular cross-operating-system emulators.
- 2 The Linux version is built on Linux as described in Build Instructions for ASCII Version on Linux.
- 3 May exhibit odd behavior or crash.
đē Gnoll Overseer
- Technological Overview of Gnoll Overseer â The technology stack of Gnoll Overseer, our AI-powered game assistant.
đ¤ AI
- AI Skills â GnollHack development-related skills to be used with AI agents
- AI Safety Settings â Gnoll Overseer safety settings